<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Configure Elasticsearch for SAML authentication | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'saml-guide-authentication.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/saml-guide-authentication.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/saml-guide-authentication.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/saml-guide-authentication.html" rel="nofollow" target="_blank">../en/saml-guide-authentication.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="saml-guide.html">Configuring SAML single-sign-on on the Elastic Stack</a></span>
»
<span class="breadcrumb-node">Configure Elasticsearch for SAML authentication</span>
</div>
<div class="navheader">
<span class="prev">
<a href="saml-guide-idp.html">« The identity provider</a>
</span>
<span class="next">
<a href="saml-sp-metadata.html">Generating SP metadata »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="saml-guide-authentication"></a>Configure Elasticsearch for SAML authentication<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h2>
</div></div></div>
<p>There are five configuration steps to enable SAML authentication in Elasticsearch:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<a class="xref" href="saml-guide-authentication.html#saml-enable-http" title="Enable TLS for HTTP">Enable SSL/TLS for HTTP</a>
</li>
<li class="listitem">
<a class="xref" href="saml-guide-authentication.html#saml-enable-token" title="Enable the token service">Enable the Token Service</a>
</li>
<li class="listitem">
<a class="xref" href="saml-guide-authentication.html#saml-create-realm" title="Create a SAML realm">Create one or more SAML realms</a>
</li>
<li class="listitem">
<a class="xref" href="saml-role-mapping.html" title="Configuring role mappings">Configure role mappings</a>
</li>
<li class="listitem">
Generate a SAML Metadata file for use by your Identity Provider <em>(optional)</em>
</li>
</ol>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="saml-enable-http"></a>Enable TLS for HTTP<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>If your Elasticsearch cluster is operating in production mode, then you must
configure the HTTP interface to use SSL/TLS before you can enable SAML
authentication.</p>
<p>For more information, see
<a class="xref" href="configuring-tls.html#tls-http" title="Encrypting HTTP client communications">Encrypting HTTP client communications</a>.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="saml-enable-token"></a>Enable the token service<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The Elasticsearch SAML implementation makes use of the Elasticsearch Token Service.  This service
is automatically enabled if you configure TLS on the HTTP interface, and can be
explicitly configured by including the following in your <code class="literal">elasticsearch.yml</code> file:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack.security.authc.token.enabled: true</pre>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="saml-create-realm"></a>Create a SAML realm<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>SAML authentication is enabled by configuring a SAML realm within the
authentication chain for Elasticsearch.</p>
<p>This realm has a few mandatory settings, and a number of optional settings.
The available settings are described in detail in <a class="xref" href="security-settings.html" title="Security settings in Elasticsearch">Security settings</a>. For
example, <a class="xref" href="security-settings.html#ref-saml-settings" title="SAML realm settings">SAML realm settings</a>, <a class="xref" href="security-settings.html#ref-saml-signing-settings" title="SAML realm signing settings">SAML realm signing settings</a>,
<a class="xref" href="security-settings.html#ref-saml-encryption-settings" title="SAML realm encryption settings">SAML realm encryption settings</a>, <a class="xref" href="security-settings.html#ref-saml-ssl-settings" title="SAML realm SSL settings">SAML realm SSL settings</a>.
This guide will walk you through the most common settings.</p>
<p>Create a realm by adding the following to your <code class="literal">elasticsearch.yml</code>
configuration file. Each configuration value is explained below.</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack.security.authc.realms.saml.saml1:
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.example.com/"
  sp.acs: "https://kibana.example.com/api/security/v1/saml"
  sp.logout: "https://kibana.example.com/logout"
  attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
  attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."</pre>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>SAML is used when authenticating via Kibana, but it is not an
effective means of authenticating directly to the Elasticsearch REST API. For this reason
we recommend that you include at least one additional realm such as the
<a class="xref" href="native-realm.html" title="Native user authentication">native realm</a> in your authentication chain for use by API
clients.</p>
</div>
</div>
<p>The configuration values used in the example above are:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
xpack.security.authc.realms.saml.saml1
</span>
</dt>
<dd>
This defines a new <code class="literal">saml</code> authentication realm named "saml1".
See <a class="xref" href="realms.html" title="Realms">Realms</a> for more explanation of realms.
</dd>
<dt>
<span class="term">
order
</span>
</dt>
<dd>
You should define a unique order on each realm in your authentication chain.
It is recommended that the SAML realm be at the bottom of your authentication
chain (that is, that it has the <em>highest</em> order).
</dd>
<dt>
<span class="term">
idp.metadata.path
</span>
</dt>
<dd>
This is the path to the metadata file that you saved for your Identity Provider.
The path that you enter here is relative to your <code class="literal">config/</code> directory.
Elasticsearch will automatically monitor this file for changes and will
reload the configuration whenever it is updated.
</dd>
<dt>
<span class="term">
idp.entity_id
</span>
</dt>
<dd>
This is the identifier (SAML EntityID) that your IdP uses.
It should match the <code class="literal">entityID</code> attribute within the metadata file.
</dd>
<dt>
<span class="term">
sp.entity_id
</span>
</dt>
<dd>
This is a unique identifier for your Kibana instance, expressed as a URI.
You will use this value when you add Kibana as a service provider within your IdP.
We recommend that you use the base URL for your Kibana instance as the entity ID.
</dd>
<dt>
<span class="term">
sp.acs
</span>
</dt>
<dd>
The <em>Assertion Consumer Service</em> (ACS) endpoint is the URL within Kibana that accepts
authentication messages from the IdP.
This ACS endpoint supports the SAML HTTP-POST binding only.
It must be a URL that is accessible from the web browser of the user who is
attempting to login to Kibana, it does not need to be directly accessible by Elasticsearch
or the IdP.
The correct value may vary depending on how you have installed Kibana and
whether there are any proxies involved, but it will typically be
<code class="literal">${kibana-url}/api/security/v1/saml</code> where <em>${kibana-url}</em> is the base URL for
your Kibana instance.
</dd>
<dt>
<span class="term">
sp.logout
</span>
</dt>
<dd>
This is the URL within Kibana that accepts logout messages from the IdP.
Like the <code class="literal">sp.acs</code> URL, it must be accessible from the web browser, but does
not need to be directly accessible by Elasticsearch or the IdP. The correct value may
vary depending on how you have installed Kibana and whether there are any
proxies involved, but it will typically be <code class="literal">${kibana-url}/logout</code> where
<em>${kibana-url}</em> is the base URL for your Kibana instance.
</dd>
<dt>
<span class="term">
attribute.principal
</span>
</dt>
<dd>
See <a class="xref" href="saml-guide-authentication.html#saml-attribute-mapping" title="Attribute mapping">Attribute mapping</a>.
</dd>
<dt>
<span class="term">
attribute.groups
</span>
</dt>
<dd>
See <a class="xref" href="saml-guide-authentication.html#saml-attribute-mapping" title="Attribute mapping">Attribute mapping</a>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="saml-attribute-mapping"></a>Attribute mapping<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>When a user connects to Kibana through your Identity Provider, the Identity
Provider will supply a SAML Assertion about the user. The assertion will contain
an <em>Authentication Statement</em> indicating that the user has successfully
authenticated to the IdP and one or more <em>Attribute Statements</em> that will
include <em>Attributes</em> for the user.</p>
<p>These attributes may include such things as:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
the user’s username
</li>
<li class="listitem">
the user’s email address
</li>
<li class="listitem">
the user’s groups or roles
</li>
</ul>
</div>
<p>Attributes in SAML are named using a URI such as
<code class="literal">urn:oid:0.9.2342.19200300.100.1.1</code> or
<code class="literal">http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn</code>, and have one or
more values associated with them.</p>
<p>These attribute identifiers vary between IdPs, and most IdPs offer ways to
customize the URIs and their associated value.</p>
<p>Elasticsearch uses these attributes to infer information about the user who has
logged in, and they can be used for role mapping (below).</p>
<p>In order for these attributes to be useful, Elasticsearch and the IdP need to have a
common value for the names of the attributes. This is done manually, by
configuring the IdP and the SAML realm to use the same URI name for
each logical user attribute.</p>
<p>The recommended steps for configuring these SAML attributes are as follows:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
Consult your IdP to see what user attributes it can provide.
This varies greatly between providers, but you should be able to obtain a list
from the documentation, or from your local admin.
</li>
<li class="listitem">
Read through the list of <a class="xref" href="saml-guide-authentication.html#saml-user-properties" title="Elasticsearch user properties">user properties</a> that Elasticsearch
supports, and decide which of them are useful to you, and can be provided by
your IdP. At a <em>minimum</em>, the <code class="literal">principal</code> attribute is required.
</li>
<li class="listitem">
Configure your IdP to "release" those attributes to your Kibana SAML service
provider.  This process varies by provider - some will provide a user interface
for this, while others may require that you edit configuration files.
Usually the IdP (or your local administrator) will have suggestions about what
URI to use for each attribute. You can simply accept those suggestions, as the
Elasticsearch service is entirely configurable and does not require that any specific
URIs are used.
</li>
<li class="listitem">
Configure the SAML realm in Elasticsearch to associate the Elasticsearch user properties (see
<a class="xref" href="saml-guide-authentication.html#saml-user-properties" title="Elasticsearch user properties">the listing</a> below), to the URIs that you configured
in your IdP. In the example above, we have configured the <code class="literal">principal</code> and
<code class="literal">groups</code> attributes.
</li>
</ol>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="saml-attribute-mapping-nameid"></a>Special attribute names<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>In general, Elasticsearch expects that the configured value for an attribute will be a
URI such as <code class="literal">urn:oid:0.9.2342.19200300.100.1.1</code>, however there are some
additional names that can be used:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">nameid</code>
</span>
</dt>
<dd>
This uses the SAML <code class="literal">NamedID</code> value instead of a SAML attribute. SAML
<code class="literal">NameID</code> elements are an optional, but frequently provided, field within a
SAML Assertion that the IdP may use to identify the Subject of that
Assertion. In some cases the <code class="literal">NameID</code> will relate to the user’s login
identifier (username) within the IdP, but in many cases they will be
internally generated identifiers that have no obvious meaning outside
of the IdP.
</dd>
<dt>
<span class="term">
<code class="literal">nameid:persistent</code>
</span>
</dt>
<dd>
This uses the SAML <code class="literal">NameID</code> value, but only if the NameID format is
<code class="literal">urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</code>.
A SAML <code class="literal">NameID</code> element has an optional <code class="literal">Format</code> attribute that indicates
the semantics of the provided name.  It is common for IdPs to be configured
with "transient" NameIDs that present a new identifier for each session.
Since it is rarely useful to use a transient NameID as part of an attribute
mapping, the "nameid:persistent" attribute name can be used as a safety
mechanism that will cause an error if you attempt to map from a <code class="literal">NameID</code>
that does not have a persistent value.
</dd>
<dt>
<span class="term">
<em>friendlyName</em>
</span>
</dt>
<dd>
A SAML attribute may have a <em>friendlyName</em> in addition to its URI based name.
For example the attribute with a name of <code class="literal">urn:oid:0.9.2342.19200300.100.1.1</code>
might also have a friendlyName of <code class="literal">uid</code>.
You may use these friendly names within an attribute mapping, but it is
recommended that you use the URI based names, as friendlyNames are neither
standardized or mandatory.
</dd>
</dl>
</div>
<p>The example below configures a realm to use a persistent nameid for the principal,
and the attribute with the friendlyName "roles" for the user’s groups.</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack.security.authc.realms.saml.saml1:
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.example.com/"
  sp.acs: "https://kibana.example.com/api/security/v1/saml"
  attributes.principal: "nameid:persistent"
  attributes.groups: "roles"</pre>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="saml-user-properties"></a>Elasticsearch user properties<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The Elasticsearch SAML realm can be configured to map SAML <code class="literal">attributes</code> to the
following properties on the authenticated user:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
principal
</span>
</dt>
<dd>
<em>(Required)</em>
This is the <em>username</em> that will be applied to a user that authenticates
against this realm.
The <code class="literal">principal</code> appears in places such as the Elasticsearch audit logs.
</dd>
<dt>
<span class="term">
groups
</span>
</dt>
<dd>
<em>(Recommended)</em>
If you wish to use your IdP’s concept of groups or roles as the basis for a
user’s Elasticsearch privileges, you should map them with this attribute.
The <code class="literal">groups</code> are passed directly to your
<a class="xref" href="saml-role-mapping.html" title="Configuring role mappings">role mapping rules</a>
</dd>
<dt>
<span class="term">
name
</span>
</dt>
<dd>
<em>(Optional)</em> The user’s full name.
</dd>
<dt>
<span class="term">
mail
</span>
</dt>
<dd>
<em>(Optional)</em> The user’s email address.
</dd>
<dt>
<span class="term">
dn
</span>
</dt>
<dd>
<em>(Optional)</em> The user’s X.500 <em>Distinguished Name</em>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_extracting_partial_values_from_saml_attributes"></a>Extracting partial values from SAML attributes<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>There are some occasions where the IdP’s attribute may contain more information
than you wish to use within Elasticsearch. A common example of this is one where the
IdP works exclusively with email addresses, but you would like the user’s
<code class="literal">principal</code> to use the <em>local-name</em> part of the email address.
For example if their email address was <code class="literal">james.wong@staff.example.com</code>, then you
would like their principal to simply be <code class="literal">james.wong</code>.</p>
<p>This can be achieved using the <code class="literal">attribute_patterns</code> setting in the Elasticsearch
realm, as demonstrated in the realm configuration below:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack.security.authc.realms.saml.saml1:
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.example.com/"
  sp.acs: "https://kibana.example.com/api/security/v1/saml"
  attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  attribute_patterns.principal: "^([^@]+)@staff\\.example\\.com$"</pre>
</div>
<p>In this case, the user’s <code class="literal">principal</code> is mapped from an email attribute, but a
regular expression is applied to the value before it is assigned to the user.
If the regular expression matches, then the result of the first group is used as
effective value. If the regular expression does not match then the attribute
mapping fails.</p>
<p>In this example, the email address must belong to the <code class="literal">staff.example.com</code> domain,
and then the local-part (anything before the <code class="literal">@</code>) is used as the principal.
Any users who try to login using a different email domain will fail because the
regular expression will not match against their email address, and thus their
principal attribute - which is mandatory - will not be populated.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>Small mistakes in these regular expressions can have significant
security consequences. For example, if we accidentally left off the trailing
<code class="literal">$</code> from the example above, then we would match any email address where the
domain starts with <code class="literal">staff.example.com</code>, and this would accept an email
address such as <code class="literal">admin@staff.example.com.attacker.net</code>. It is important that
you make sure your regular expressions are as precise as possible so that
you do not inadvertently open an avenue for user impersonation attacks.</p>
</div>
</div>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="req-authn-context"></a>Requesting specific authentication methods<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>It is sometimes necessary for a SAML SP to be able to impose specific
restrictions regarding the authentication that will take place at an IdP,
in order to assess the level of confidence that it can place in
the corresponding authentication response. The restrictions might have to do
with the authentication method (password, client certificates, etc), the
user identification method during registration, and other details. Elasticsearch implements
<a href="https://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf" class="ulink" target="_top">SAML 2.0 Authentication Context</a>, which can be used for this purpose as defined in SAML 2.0 Core
Specification.</p>
<p>In short, the SAML SP defines a set of Authentication Context Class Reference
values, which describe the restrictions to be imposed on the IdP, and sends these
in the Authentication Request. The IdP attempts to grant these restrictions.
If it cannot grant them, the authentication attempt fails. If the user is
successfully authenticated, the Authentication Statement of the SAML Response
contains an indication of the restrictions that were satisfied.</p>
<p>You can define the Authentication Context Class Reference values by using the <code class="literal">req_authn_context_class_ref</code> option in the SAML realm configuration. See
<a class="xref" href="security-settings.html#ref-saml-settings" title="SAML realm settings">SAML realm settings</a>.</p>
<p>Elasticsearch supports only the <code class="literal">exact</code> comparison method for the Authentication Context.
When it receives the Authentication Response from the IdP, Elasticsearch examines the
value of the Authentication Context Class Reference that is part of the
Authentication Statement of the SAML Assertion. If it matches one of the
requested values, the authentication is considered successful. Otherwise, the
authentication attempt fails.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="saml-logout"></a>SAML logout<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The SAML protocol supports the concept of Single Logout (SLO).
The level of support for SLO varies between Identity Providers.
You should consult the documentation for your IdP to determine what Logout
services it offers.</p>
<p>By default the Elastic Stack will support SAML SLO if the following are true:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Your IdP metadata specifies that the IdP offers a SLO service
</li>
<li class="listitem">
Your IdP releases a NameID in the subject of the SAML assertion that it issues for your users
</li>
<li class="listitem">
You configure <code class="literal">sp.logout</code>
</li>
<li class="listitem">
The setting <code class="literal">idp.use_single_logout</code> is not <code class="literal">false</code>
</li>
</ul>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_idp_slo_service"></a>IdP SLO service<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>One of the values that Elasticsearch reads from the IdP’s SAML metadata is the
<code class="literal">&lt;SingleLogoutService&gt;</code>. In order for Single Logout to work with the Elastic
stack, Elasticsearch requires that this exist and support a binding of
<code class="literal">urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</code>.</p>
<p>The Elastic Stack will send both <code class="literal">&lt;LogoutRequest&gt;</code> and <code class="literal">&lt;LogoutResponse&gt;</code>
messages to this service as appropriate.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_the_sp_logout_setting"></a>The sp.logout setting<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The Elasticsearch realm setting <code class="literal">sp.logout</code> specifies a URL in Kibana to which the IdP can
send both <code class="literal">&lt;LogoutRequest&gt;</code> and <code class="literal">&lt;LogoutResponse&gt;</code> messages. This service uses
the SAML HTTP-Redirect binding.</p>
<p>Elasticsearch will process <code class="literal">&lt;LogoutRequest&gt;</code> messages, and perform a global signout that
invalidates any existing Elasticsearch security tokens that are associated with the
provided SAML session.</p>
<p>If you do not configure a value for <code class="literal">sp.logout</code>, Elasticsearch will refuse all
<code class="literal">&lt;LogoutRequest&gt;</code> messages.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>It is common for IdPs to require that <code class="literal">LogoutRequest</code> messages be signed,
so you may need to configure <a class="xref" href="saml-guide-authentication.html#saml-enc-sign" title="Encryption and signing">signing credentials</a>.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_the_idp_use_single_logout_setting"></a>The idp.use_single_logout setting<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>If your IdP provides a <code class="literal">&lt;SingleLogoutService&gt;</code> but you do not wish to use it,
you can configure <code class="literal">idp.use_single_logout: false</code> in your SAML realm, and Elasticsearch
will ignore the SLO service that your IdP provides. In this case, when a user
logs out of Kibana it will invalidate their Elasticsearch session (security token), but
will not perform any logout at the IdP.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_using_kibana_without_single_logout"></a>Using Kibana without single logout<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>If your IdP does not support Single Logout, or you choose not to use it, then
Kibana will perform a "local logout" only.</p>
<p>This means that Kibana will invalidate the session token it is using to
communicate with Elasticsearch, but will not be able to perform any sort of invalidation
of the Identity Provider session. In most cases this will mean that Kibana users
are still considered to be logged in to the IdP. Consequently, if the user
navigates to the Kibana landing page, they will be automatically reauthenticated,
and will commence a new Kibana session without needing to enter any credentials.</p>
<p>The possible solutions to this problem are:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Ask your IdP administrator or vendor to provide a Single Logout service
</li>
<li class="listitem">
If your Idp does provide a Single Logout Service, make sure it is included in
the IdP metadata file, and do <em>not</em> set <code class="literal">idp.use_single_logout</code> to <code class="literal">false</code>.
</li>
<li class="listitem">
Advise your users to close their browser after logging out of Kibana
</li>
<li class="listitem">
Enable the <code class="literal">force_authn</code> setting on your SAML realm. This setting causes the
Elastic Stack to request fresh authentication from the IdP every time a user
attempts to log into Kibana.
This setting defaults to <code class="literal">false</code> because it can be a more cumbersome user
experience, but it can also be an effective protection to stop users
piggy-backing on existing IdP sessions.
</li>
</ul>
</div>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="saml-enc-sign"></a>Encryption and signing<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The Elastic Stack supports generating signed SAML messages (for authentication
and/or logout), verifying signed SAML messages from the IdP (for both
authentication and logout) and can process encrypted content.</p>
<p>You can configure Elasticsearch for signing, encryption or both, with the same
or separate keys used for each of those.</p>
<p>The Elastic Stack uses X.509 certificates with RSA private keys for SAML
cryptography. These keys can be generated using any standard SSL tool, including
the <code class="literal">elasticsearch-certutil</code> tool.</p>
<p>Your IdP may require that the Elastic Stack have a cryptographic key for signing
SAML messages, and that you provide the corresponding signing certificate within
the Service Provider configuration (either within the Elastic Stack SAML
metadata file or manually configured within the IdP administration interface).
While most IdPs do not expected authentication requests to be signed, it is
commonly the case that signatures are required for logout requests. Your IdP
will validate these signatures against the signing certificate that has been
configured for the Elastic Stack Service Provider.</p>
<p>Encryption certificates are rarely needed, but the Elastic Stack supports them
for cases where IdPs or local policies mandate their use.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_generating_certificates_and_keys"></a>Generating certificates and keys<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Elasticsearch supports certificates and keys in either PEM, PKCS#12 or JKS format.
Some Identity Providers are more restrictive in the formats they support, and
will require you to provide the certificates as a file in a particular format.
You should consult the documentation for your IdP to determine what formats they
support. Since PEM format is the most commonly supported format, the examples
below will generate certificates in that format.</p>
<p>Using the <a class="xref" href="certutil.html" title="elasticsearch-certutil"><code class="literal">elasticsearch-certutil</code> tool</a>, you can generate a
signing certificate with the following command:</p>
<div class="pre_wrapper lang-sh">
<pre class="programlisting prettyprint lang-sh">bin/elasticsearch-certutil cert -pem -days 1100 -name saml-sign -out saml-sign.zip</pre>
</div>
<p>This will</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
generate a certificate and key pair (the <code class="literal">cert</code> subcommand)
</li>
<li class="listitem">
create the files in PEM format (<code class="literal">-pem</code> option)
</li>
<li class="listitem">
generate a certificate that is valid for 3 years (<code class="literal">-days 1100</code>)
</li>
<li class="listitem">
name the certificate <code class="literal">saml-sign</code> (<code class="literal">-name</code> option)
</li>
<li class="listitem">
save the certificate and key in the <code class="literal">saml-sign.zip</code> file (<code class="literal">-out</code> option)
</li>
</ul>
</div>
<p>The generated zip archive will contain 3 files:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">saml-sign.crt</code>, the public certificate to be used for signing
</li>
<li class="listitem">
<code class="literal">saml-sign.key</code>, the private key for the certificate
</li>
<li class="listitem">
<code class="literal">ca.crt</code>, a CA certificate that is not need, and can be ignored.
</li>
</ul>
</div>
<p>Encryption certificates can be generated with the same process.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_configuring_elasticsearch_for_signing"></a>Configuring Elasticsearch for signing<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>By default, Elasticsearch will sign <em>all</em> outgoing SAML messages if a signing
key has been configured.</p>
<p>If you wish to use <span class="strong strong"><strong>PEM formatted</strong></span> keys and certificates for signing, then
you should configure the following settings on the SAML realm:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">signing.certificate</code>
</span>
</dt>
<dd>
The path to the PEM formatted certificate file. e.g. <code class="literal">saml/saml-sign.crt</code>
</dd>
<dt>
<span class="term">
<code class="literal">signing.key</code>
</span>
</dt>
<dd>
The path to the PEM formatted key file. e.g. <code class="literal">saml/saml-sign.key</code>
</dd>
<dt>
<span class="term">
<code class="literal">signing.secure_key_passphrase</code>
</span>
</dt>
<dd>
The passphrase for the key, if the file is encrypted. This is a
<a class="xref" href="secure-settings.html" title="Secure settings">secure setting</a> that must be set with the
<code class="literal">elasticsearch-keystore</code> tool.
</dd>
</dl>
</div>
<p>If you wish to use <span class="strong strong"><strong>PKCS#12 formatted</strong></span> files or a <span class="strong strong"><strong>Java Keystore</strong></span> for
signing, then you should configure the following settings on the SAML realm:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">signing.keystore.path</code>
</span>
</dt>
<dd>
The path to the PKCS#12 or JKS keystore. e.g. <code class="literal">saml/saml-sign.p12</code>
</dd>
<dt>
<span class="term">
<code class="literal">signing.keystore.alias</code>
</span>
</dt>
<dd>
The alias of the key within the keystore. e.g. <code class="literal">signing-key</code>
</dd>
<dt>
<span class="term">
<code class="literal">signing.keystore.secure_password</code>
</span>
</dt>
<dd>
The passphrase for the keystore, if the file is encrypted. This is a
<a class="xref" href="secure-settings.html" title="Secure settings">secure setting</a> that must be set with the
<code class="literal">elasticsearch-keystore</code> tool.
</dd>
</dl>
</div>
<p>If you wish to sign some, but not all outgoing <span class="strong strong"><strong>SAML messages</strong></span>, then you
should configure the following setting on the SAML realm:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">signing.saml_messages</code>
</span>
</dt>
<dd>
A list of message types to sign. A message type is identified by the
<em>local name</em> of the XML element used for the message. Supported values
are: <code class="literal">AuthnRequest</code>, <code class="literal">LogoutRequest</code> and <code class="literal">LogoutResponse</code>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_configuring_elasticsearch_for_encrypted_messages"></a>Configuring Elasticsearch for encrypted messages<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/saml-guide.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The Elasticsearch security features support a single key for message decryption. If a
key is configured, then Elasticsearch attempts to use it to decrypt
<code class="literal">EncryptedAssertion</code> and <code class="literal">EncryptedAttribute</code> elements in Authentication
responses, and <code class="literal">EncryptedID</code> elements in Logout requests.</p>
<p>Elasticsearch rejects any SAML message that contains an <code class="literal">EncryptedAssertion</code>
that cannot be decrypted.</p>
<p>If an <code class="literal">Assertion</code> contains both encrypted and plain-text attributes, then
failure to decrypt the encrypted attributes will not cause an automatic
rejection. Rather, Elasticsearch processes the available plain-text attributes
(and any <code class="literal">EncryptedAttributes</code> that could be decrypted).</p>
<p>If you wish to use <span class="strong strong"><strong>PEM formatted</strong></span> keys and certificates for SAML encryption,
then you should configure the following settings on the SAML realm:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">encryption.certificate</code>
</span>
</dt>
<dd>
The path to the PEM formatted certificate file. e.g. <code class="literal">saml/saml-crypt.crt</code>
</dd>
<dt>
<span class="term">
<code class="literal">encryption.key</code>
</span>
</dt>
<dd>
The path to the PEM formatted key file. e.g. <code class="literal">saml/saml-crypt.key</code>
</dd>
<dt>
<span class="term">
<code class="literal">encryption.secure_key_passphrase</code>
</span>
</dt>
<dd>
The passphrase for the key, if the file is encrypted. This is a
<a class="xref" href="secure-settings.html" title="Secure settings">secure setting</a> that must be set with the
<code class="literal">elasticsearch-keystore</code> tool.
</dd>
</dl>
</div>
<p>If you wish to use <span class="strong strong"><strong>PKCS#12 formatted</strong></span> files or a <span class="strong strong"><strong>Java Keystore</strong></span> for SAML
encryption, then you should configure the following settings on the SAML realm:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">encryption.keystore.path</code>
</span>
</dt>
<dd>
The path to the PKCS#12 or JKS keystore. e.g. <code class="literal">saml/saml-crypt.p12</code>
</dd>
<dt>
<span class="term">
<code class="literal">encryption.keystore.alias</code>
</span>
</dt>
<dd>
The alias of the key within the keystore. e.g. <code class="literal">encryption-key</code>
</dd>
<dt>
<span class="term">
<code class="literal">encryption.keystore.secure_password</code>
</span>
</dt>
<dd>
The passphrase for the keystore, if the file is encrypted. This is a
<a class="xref" href="secure-settings.html" title="Secure settings">secure setting</a> that must be set with the
<code class="literal">elasticsearch-keystore</code> tool.
</dd>
</dl>
</div>
</div>

</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="saml-guide-idp.html">« The identity provider</a>
</span>
<span class="next">
<a href="saml-sp-metadata.html">Generating SP metadata »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>